package com.southminority.ethnic.service.heritage;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.controller.heritage.vo.HeritageResearchLinkVO;
import com.southminority.ethnic.pojo.HeritageResearchLink;

import java.util.List;

/**
 * 非遗-研究成果关联服务接口.
 * <p>
 * 定义了管理非遗项目与研究成果（如论文、报告、项目等）之间关联关系的业务逻辑。
 * 
 * @author SouthMinority
 */
public interface HeritageResearchLinkService {

    /**
     * 根据非遗项目ID获取其所有已发布的研究成果关联链接列表（用于前端展示）.
     *
     * @param heritageId 非遗项目的唯一标识ID.
     * @return {@link List<HeritageResearchLinkVO>} 研究成果链接的视图对象列表.
     */
    List<HeritageResearchLinkVO> getResearchLinksByHeritageId(Long heritageId);

    /**
     * 分页查询研究成果链接（用于后台管理列表）.
     *
     * @param page       当前页码.
     * @param size       每页显示数量.
     * @param heritageId 非遗项目ID (可选, 用于筛选特定项目下的关联).
     * @param keyword    搜索关键词 (可选, 模糊匹配标题、描述).
     * @param type       关联类型 (可选).
     * @param status     状态 (可选, 1-正常, 0-禁用, -1-已删除).
     * @return {@link PageResult<HeritageResearchLinkVO>} 封装了分页信息的查询结果.
     */
    PageResult<HeritageResearchLinkVO> getResearchLinkPageForAdmin(Integer page, Integer size,
                                                                 Long heritageId, String keyword,
                                                                 String type, Integer status);

    /**
     * 根据ID获取单个研究成果链接的详细信息.
     *
     * @param id 关联链接的唯一标识ID.
     * @return {@link HeritageResearchLinkVO} 链接的视图对象.
     */
    HeritageResearchLinkVO getResearchLinkDetail(Long id);

    /**
     * 创建一个新的研究成果链接.
     *
     * @param researchLink 包含链接信息的POJO对象.
     * @return {@link HeritageResearchLinkVO} 创建成功后返回的链接视图对象.
     */
    HeritageResearchLinkVO createResearchLink(HeritageResearchLink researchLink);

    /**
     * 更新一个已存在的研究成果链接.
     *
     * @param id           要更新的链接的ID.
     * @param researchLink 包含更新后信息的POJO对象.
     * @return {@link HeritageResearchLinkVO} 更新成功后返回的链接视图对象.
     */
    HeritageResearchLinkVO updateResearchLink(Long id, HeritageResearchLink researchLink);

    /**
     * 根据ID删除一个研究成果链接（逻辑删除）.
     *
     * @param id 要删除的链接的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean deleteResearchLink(Long id);

    /**
     * 批量删除研究成果链接（逻辑删除）.
     *
     * @param ids 包含多个要删除的链接ID的列表.
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean batchDeleteResearchLink(List<Long> ids);

    /**
     * 更新指定研究成果链接的状态.
     *
     * @param id     链接的ID.
     * @param status 新的状态值 (例如: 1-正常, 0-禁用).
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean updateResearchLinkStatus(Long id, Integer status);
}
